Network PC

home *** CD-ROM | disk | FTP | other *** search

/ Network PC / Network PC.iso / amiga utilities / communication / internet / amitcp3.0b / doc / bsdsocket.doc < prev next >

Wrap

Text File | 1997-11-21 | 118.8 KB | 3,028 lines

TABLE OF CONTENTS bsdsocket.library/accept bsdsocket.library/bind bsdsocket.library/CloseSocket bsdsocket.library/connect bsdsocket.library/Dup2Socket bsdsocket.library/Errno bsdsocket.library/getdtablesize bsdsocket.library/gethostbyaddr bsdsocket.library/gethostbyname bsdsocket.library/gethostid bsdsocket.library/gethostname bsdsocket.library/getnetbyaddr bsdsocket.library/getnetbyname bsdsocket.library/getpeername bsdsocket.library/getprotobyname bsdsocket.library/getprotobynumber bsdsocket.library/getservbyname bsdsocket.library/getservbyport bsdsocket.library/getsockname bsdsocket.library/getsockopt bsdsocket.library/inet_addr bsdsocket.library/Inet_LnaOf bsdsocket.library/inet_MakeAddr bsdsocket.library/Inet_NetOf bsdsocket.library/inet_network bsdsocket.library/Inet_NtoA bsdsocket.library/IoctlSocket bsdsocket.library/listen bsdsocket.library/ObtainSocket bsdsocket.library/recv bsdsocket.library/recvfrom bsdsocket.library/ReleaseCopyOfSocket bsdsocket.library/ReleaseSocket bsdsocket.library/select bsdsocket.library/send bsdsocket.library/sendto bsdsocket.library/SetErrnoPtr bsdsocket.library/SetSocketSignals bsdsocket.library/inet_lnaof bsdsocket.library/inet_makeaddr bsdsocket.library/inet_netof bsdsocket.library/inet_ntoa bsdsocket.library/setsockopt bsdsocket.library/shutdown bsdsocket.library/socket bsdsocket.library/SocketBaseTagList bsdsocket.library/syslog protocols/arp protocols/icmp protocols/if protocols/inet protocols/ip protocols/lo protocols/routing protocols/tcp protocols/udp bsdsocket.library/accept bsdsocket.library/accept NAME accept - accept a connection on a socket SYNOPSIS #include <sys/types.h> #include <sys/socket.h> ns = accept(s, addr, addrlen) D0 D0 A0 A1 long accept(long, struct sockaddr *, long *); FUNCTION The argument s is a socket that has been created with socket(), bound to an address with bind(), and is listen- ing for connections after a listen(). accept() extracts the first connection on the queue of pending connections, creates a new socket with the same properties of s and allo- cates a new socket descriptor for the socket. If no pending connections are present on the queue, and the socket is not marked as non-blocking, accept() blocks the caller until a connection is present. If the socket is marked non-blocking and no pending connections are present on the queue, accept() returns an error as described below. The accepted socket is used to read and write data to and from the socket which connected to this one; it is not used to accept more connections. The original socket s remains open for accept- ing further connections. The argument addr is a result parameter that is filled in with the address of the connecting entity, as known to the communications layer. The exact format of the addr parame- ter is determined by the domain in which the communication is occurring. The addrlen is a value-result parameter; it should initially contain the amount of space pointed to by addr; on return it will contain the actual length (in bytes) of the address returned. This call is used with connection-based socket types, currently with SOCK_STREAM. It is possible to select() a socket for the purposes of doing an accept() by selecting it for read. RETURN VALUES accept() returns a non-negative descriptor for the accepted socket on success. On failure, it returns -1 and sets errno to indicate the error. ERRORS EBADF - The descriptor is invalid. EINTR - The operation was interrupted by a break signal. EOPNOTSUPP - The referenced socket is not of type SOCK_STREAM. EWOULDBLOCK - The socket is marked non-blocking and no con- nections are present to be accepted. SEE ALSO bind(), connect(), listen(), select(), SetSocketSignals(), socket() bsdsocket.library/bind bsdsocket.library/bind NAME bind - bind a name to a socket SYNOPSIS #include <sys/types.h> #include <sys/socket.h> success = bind(s, name, namelen) D0 D0 A0 D1 long bind(long, struct sockaddr *, long); FUNCTION bind() assigns a name to an unnamed socket. When a socket is created with socket(2) it exists in a name space (address family) but has no name assigned. bind() requests that the name pointed to by name be assigned to the socket. RETURN VALUES 0 - on success. -1 - on failure and sets errno to indicate the error. ERRORS EACCES - The requested address is protected, and the current user has inadequate permis- sion to access it. EADDRINUSE - The specified address is already in use. EADDRNOTAVAIL - The specified address is not available from the local machine. EBADF - s is not a valid descriptor. EINVAL - namelen is not the size of a valid address for the specified address fam- ily. The socket is already bound to an address. SEE ALSO connect(), getsockname(), listen(), socket() NOTES The rules used in name binding vary between communication domains. bsdsocket.library/CloseSocket bsdsocket.library/CloseSocket NAME CloseSocket - delete a socket descriptor SYNOPSIS success = CloseSocket(s) D0 D0 long CloseSocket(long); FUNCTION CloseSocket() deletes a descriptor from the library base socket reference table. If s is the last reference to the underlying object, then the object will be deactivated and socket (see socket()), associated naming information and queued data are discarded. All sockets are automatically closed when the socket library is closed, but closing sockets as soon as possible is recommended to save system resources. RETURN VALUES 0 on success. -1 on failure and sets errno to indicate the error. ERRORS EBADF - s is not an active socket descriptor. EINTR - linger on close was interrupted. The socket is closed, however. SEE ALSO accept(), SocketBaseTagList(), shutdown(), socket(), exec.library/CloseLibrary() bsdsocket.library/connect bsdsocket.library/connect NAME connect - initiate a connection on a socket SYNOPSIS #include <sys/types.h> #include <sys/socket.h> success = connect(s, name, namelen) D0 D0 A0 D1 long connect(long, struct sockaddr *, long); FUNCTION The parameter s is a socket. If it is of type SOCK_DGRAM, then this call specifies the peer with which the socket is to be associated; this address is that to which datagrams are to be sent, and the only address from which datagrams are to be received. If it is of type SOCK_STREAM, then this call attempts to make a connection to another socket. The other socket is specified by name which is an address in the communications space of the socket. Each communications space interprets the name parameter in its own way. Gen- erally, stream sockets may successfully connect() only once; datagram sockets may use connect() multiple times to change their association. Datagram sockets may dissolve the asso- ciation by connecting to an invalid address, such as a null address. RETURN VALUES 0 on success. -1 on failure and sets errno to indicate the error. ERRORS EADDRINUSE - The address is already in use. EADDRNOTAVAIL - The specified address is not available on the remote machine. EAFNOSUPPORT - Addresses in the specified address fam- ily cannot be used with this socket. EALREADY - The socket is non-blocking and a previ- ous connection attempt has not yet been completed. EBADF - s is not a valid descriptor. ECONNREFUSED - The attempt to connect was forcefully rejected. The calling program should CloseSocket() the socket descriptor, and issue another socket() call to obtain a new descriptor before attempting another connect() call. EINPROGRESS - The socket is non-blocking and the con- nection cannot be completed immediately. It is possible to select() for comple- tion by selecting the socket for writ- ing. EINTR - The operation was interrupted by a break signal. EINVAL - namelen is not the size of a valid address for the specified address fam- ily. EISCONN The socket is already connected. ENETUNREACH - The network is not reachable from this host. ETIMEDOUT - Connection establishment timed out without establishing a connection. SEE ALSO accept(), CloseSocket(), connect(), getsockname(), select(), socket() bsdsocket.library/Dup2Socket bsdsocket.library/Dup2Socket NAME Dup2Socket - duplicate a socket descriptor SYNOPSIS newfd = Dup2Socket(fd1, fd2) D0 D0 D1 long Dup2Socket(long, long); DESCRIPTION Dup2Socket() duplicates an existing socket descriptor. the argument fd1 is small non-negative value that indexes the socket on SocketBase descriptor table. The value must be less than the size of the table, which is returned by getdtablesize(). fd2 specifies the desired value of the new descriptor. If descriptor fd2 is already in use, it is first deallocated as if it were closed by CloseSocket(). If the value if fd2 is -1, the new descriptor used and returned is the lowest numbered descriptor that is not currently in use by the SocketBase. Dup2Socket() has also an feature to mark a file descriptor as being used. If fd1 is given as -1, fd2 is marked as being used socket descriptor table and it won't be allocated for any socket. This mark can be removed using CloseSocket() call. RETURN VALUES Dup2Socket() returns a new descriptor on success. On failure -1 is returned and errno is set to indicate the error. ERRORS EBADF fd1 or fd2 is not a valid active descriptor. EMFILE Too many descriptors are active. SEE ALSO accept(), CloseSocket(), getdtablesize(), SocketBaseTagList(), socket() bsdsocket.library/Errno bsdsocket.library/Errno NAME Errno - get error value after unsuccessful function call SYNOPSIS errno = Errno() D0 LONG Errno(VOID); FUNCTION When some function in socket library return an error condition value, they also set a specific error value. This error value can be extracted by this function. RESULT Error value indicating the error on last failure of some socket function call. NOTES Return value of Errno() is not changed after successful function so so it cannot be used to determine success of any function call of this library. Also, another function call to this library may change the return value of Errno() so use it right after error occurred. SEE ALSO SetErrnoPtr() bsdsocket.library/getdtablesize bsdsocket.library/getdtablesize NAME getdtablesize - get socket descriptor table size SYNOPSIS nfds = getdtablesize() D0 long getdtablesize(void); FUNCTION Return value of maximum number of open socket descriptors. Larger socket descriptor table can be allocated with SocketBaseTagList() call. SEE ALSO SocketBaseTagList() bsdsocket.library/gethostbyaddr bsdsocket.library/gethostbyaddr SEE ALSO gethostbyname() bsdsocket.library/gethostbyname bsdsocket.library/gethostbyname NAME gethostbyname, gethostbyaddr - get network host entry SYNOPSIS #include <sys/types.h> #include <sys/socket.h> #include <netdb.h> hostent = gethostbyname(name) D0 A0 struct hostent *gethostbyname(char *); hostent = gethostbyaddr(addr, len, type) D0 A0 D0 D1 struct hostent *gethostbyaddr(caddr_t, LONG, LONG); DESCRIPTION gethostbyname() and gethostbyaddr() both return a pointer to an object with the following structure containing the data received from a name server or the broken-out fields of a line in netdb configuration file. In the case of gethostbyaddr(), addr is a pointer to the binary format address of length len (not a character string) and type is an address family as defined in <sys/socket.h>. struct hostent { char *h_name; /* official name of host */ char **h_aliases; /* alias list */ int h_addrtype; /* address type */ int h_length; /* length of address */ char **h_addr_list; /* list of addresses from name server */ }; The members of this structure are: h_name Official name of the host. h_aliases A zero terminated array of alternate names for the host. h_addrtype The type of address being returned; currently always AF_INET. h_length The length, in bytes, of the address. h_addr_list A pointer to a list of network addresses for the named host. Host addresses are returned in network byte order. DIAGNOSTICS A NULL pointer is returned if no matching entry was found or error occured. BUGS All information is contained in a static area so it must be copied if it is to be saved. Only the Internet address for- mat is currently understood. SEE ALSO AmiTCP/IP configuration bsdsocket.library/gethostid bsdsocket.library/gethostid NAME gethostid -- get an unique 32-bit id to this host SYNOPSIS id = gethostid(); ULONG gethostid(void); FUNCTION Return the 32-bit unique id for this host. The Internet address if the primary interface is used as the unique id. This means that this function is also a supported way to get the hosts IP address in AmiTCP/IP. If no interfaces are configured, zero is returned. Any non-loobpack interface with is preferred. Only if no other interfaces are present, is the loopback address returned. INPUTS RESULT id - non-zero on success. EXAMPLE ULONG id; id = gethostid(); if (id == 0) exit(10); printf("My primary IP address is: %s.\n", Inet_NtoA(id)); NOTES Non-zero id is returned as soon as a interface is configured. After that the id will not change, not even if the id is the address of the loopback interface. BUGS SEE ALSO bsdsocket.library/gethostname bsdsocket.library/gethostname NAME gethostname -- get the name of the host SYNOPSIS error = gethostname(name, namelen); long gethostname(char *, long); FUNCTION Get the name of the host to the buffer name of length namelen. The name is queried from the netdb and/or the name server if it is not explicitly configured (configuration variable HOSTNAME). INPUTS name - Pointer to the buffer where the name should be stored. namelen - Length of the buffer name. RESULT error - 0 on success. EXAMPLE char hostname[MAXHOSTNAMELEN]; long error; error = gethostname(hostname, sizeof(hostname)); if (error < 0) exit(10); printf("My name is \"%s\".\n", hostname); NOTES BUGS Unlike the Unix version, this version assures that the resulting string is always NULL-terminated. SEE ALSO gethostid() bsdsocket.library/getnetbyaddr bsdsocket.library/getnetbyaddr SEE ALSO getnetbyname() bsdsocket.library/getnetbyname bsdsocket.library/getnetbyname NAME getnetbyname, getnetbyaddr - get network entry SYNOPSIS #include <netdb.h> netent = getnetbyname(name) D0 A0 struct netent *getnetbyname(char *); netent = getnetbyaddr(net, type) D0 D0 D1 struct netent *getnetbyaddr(long, long); DESCRIPTION getnetbyname(), and getnetbyaddr() both return a pointer to an object with the following structure containing the broken-out fields of a line in netdb configuration file. struct netent { char *n_name; /* official name of net */ char **n_aliases; /* alias list */ int n_addrtype; /* net number type */ long n_net; /* net number */ }; The members of this structure are: n_name The official name of the network. n_aliases A zero terminated list of alternate names for the network. n_addrtype The type of the network number returned; currently only AF_INET. n_net The network number. Network numbers are returned in machine byte order. Network numbers are supplied in host order. Type specifies the address type to use, currently only AF_INET is supported. DIAGNOSTICS A NULL pointer is returned if no matching entry was found or error occured. BUGS All information is contained in a static area so it must be copied if it is to be saved. Only Internet network numbers are currently understood. SEE ALSO AmiTCP/IP configuration bsdsocket.library/getpeername bsdsocket.library/getpeername NAME getpeername - get name of connected peer SYNOPSIS success = getpeername(s, name, namelen) D0 D0 A0 A1 long getpeername(long, struct sockaddr *, long *); FUNCTION getpeername() returns the name of the peer connected to socket s. The long pointed to by the namelen parameter should be initialized to indicate the amount of space pointed to by name. On return it contains the actual size of the name returned (in bytes). The name is truncated if the buffer provided is too small. RETURN VALUE A 0 is returned if the call succeeds, -1 if it fails. ERRORS EBADF - The argument s is not a valid descriptor. ENOBUFS - Insufficient resources were available in the system to perform the operation. ENOTCONN - The socket is not connected. SEE ALSO accept(), bind(), getsockname(), socket() bsdsocket.library/getprotobyname bsdsocket.library/getprotobyname NAME getprotobyname, getprotobynumber - get protocol entry SYNOPSIS #include <netdb.h> protoent = getprotobyname(name) D0 A0 struct protoent *getprotobyname(char *); protoent = getprotobynumber(proto) D0 D0 struct protoent *getprotobynumber(long); DESCRIPTION getprotobyname() and getprotobynumber() both return a pointer to an object with the following structure containing the broken-out fields of a line in netdb configuration file struct protoent { char *p_name; /* official name of protocol */ char **p_aliases; /* alias list */ int p_proto; /* protocol number */ }; The members of this structure are: p_name The official name of the protocol. p_aliases A zero terminated list of alternate names for the protocol. p_proto The protocol number. DIAGNOSTICS A NULL pointer is returned if no matching entry was found or error occured. BUGS All information is contained in a static area so it must be copied if it is to be saved. Only the Internet protocols are currently understood. SEE ALSO AmiTCP/IP configuration bsdsocket.library/getprotobynumber bsdsocket.library/getprotobynumber SEE ALSO getprotobyname() bsdsocket.library/getservbyname bsdsocket.library/getservbyname NAME getservbyname, getservbyport - get service entry SYNOPSIS #include <netdb.h> servent = getservbyname(name, proto) D0 A0 A1 struct servent *getservbyname(char *, char *) servent = getservbyport(port, proto) D0 D0 A0 struct servent *getservbyport(long, char *); DESCRIPTION getservbyname() and getservbyport() both return a pointer to an object with the following structure containing the broken-out fields of a line in netdb configuration file. struct servent { char *s_name; /* official name of service */ char **s_aliases; /* alias list */ int s_port; /* port service resides at */ char *s_proto; /* protocol to use */ }; The members of this structure are: s_name The official name of the service. s_aliases A zero terminated list of alternate names for the service. s_port The port number at which the ser- vice resides. Port numbers are returned in network short byte order. s_proto The name of the protocol to use when contacting the service. The proto argument specifies the protocol for which to the sercive is to use. It is a normal C string, e.g. "tcp" or "udp". DIAGNOSTICS A NULL pointer is returned if no matching entry was found or error occured. BUGS All information is contained in a static area so it must be copied if it is to be saved. Expecting port numbers to fit in a 32 bit quantity is probably naive. SEE ALSO AmiTCP/IP configuration bsdsocket.library/getservbyport bsdsocket.library/getservbyport SEE ALSO getservbyname() bsdsocket.library/getsockname bsdsocket.library/getsockname NAME getsockname - get socket name SYNOPSIS success = getsockname(s, name, namelen) D0 D0 A0 A1 long getsockname(long, struct sockaddr *, long *); FUNCTION getsockname() returns the current name for the specified socket. The namelen parameter should be initialized to indicate the amount of space pointed to by name. On return it contains the actual size of the name returned (in bytes). DIAGNOSTICS A 0 is returned if the call succeeds, -1 if it fails. ERRORS The call succeeds unless: EBADF s is not a valid descriptor. ENOBUFS Insufficient resources were available in the system to perform the operation. SEE ALSO bind(), getpeername(), socket() bsdsocket.library/getsockopt bsdsocket.library/getsockopt NAME getsockopt, setsockopt - get and set options on sockets SYNOPSIS #include <sys/types.h> #include <sys/socket.h> success = getsockopt(s, level, optname, optval, optlen) D0 D0 D1 D2 A0 A1 long getsockopt(long, long, long, caddr_t, long *); success = setsockopt(s, level, optname, optval, optlen) D0 D0 D1 D2 A0 D3 long setsockopt(long, long, long, caddr_t, long); FUNCTION getsockopt() and setsockopt() manipulate options associated with a socket. Options may exist at multiple protocol lev- els; they are always present at the uppermost ``socket'' level. When manipulating socket options the level at which the option resides and the name of the option must be specified. To manipulate options at the ``socket'' level, level is specified as SOL_SOCKET. To manipulate options at any other level the protocol number of the appropriate protocol con- trolling the option is supplied. For example, to indicate that an option is to be interpreted by the TCP protocol, level should be set to the protocol number of TCP. The parameters optval and optlen are used to access option values for setsockopt(). For getsockopt() they identify a buffer in which the value for the requested option(s) are to be returned. For getsockopt(), optlen is a value-result parameter, initially containing the size of the buffer pointed to by optval, and modified on return to indicate the actual size of the value returned. If no option value is to be supplied or returned, optval may be supplied as 0. optname and any specified options are passed uninterpreted to the appropriate protocol module for interpretation. The include file <sys/socket.h> contains definitions for ``socket'' level options, described below. Options at other protocol levels vary in format and name. Most socket-level options take an int parameter for optval. For setsockopt(), the parameter should be non-zero to enable a boolean option, or zero if the option is to be disabled. SO_LINGER uses a struct linger parameter, defined in <sys/socket.h>, which specifies the desired state of the option and the linger interval (see below). The following options are recognized at the socket level. Except as noted, each may be examined with getsockopt() and set with setsockopt(). SO_DEBUG - toggle recording of debugging information SO_REUSEADDR - toggle local address reuse SO_KEEPALIVE - toggle keep connections alive SO_DONTROUTE - toggle routing bypass for outgoing messages SO_LINGER - linger on close if data present SO_BROADCAST - toggle permission to transmit broadcast messages SO_OOBINLINE - toggle reception of out-of-band data in band SO_SNDBUF - set buffer size for output SO_RCVBUF - set buffer size for input SO_TYPE - get the type of the socket (get only) SO_ERROR - get and clear error on the socket (get only) SO_DEBUG enables debugging in the underlying protocol modules. SO_REUSEADDR indicates that the rules used in validating addresses supplied in a bind() call should allow reuse of local addresses. SO_KEEPALIVE enables the periodic transmission of messages on a connected socket. Should the connected party fail to respond to these messages, the con- nection is considered broken. If the process is waiting in select() when the connection is broken, select() returns true for any read or write events selected for the socket. SO_DONTROUTE indicates that outgoing messages should bypass the standard routing facilities. Instead, messages are directed to the appropriate network interface according to the network portion of the destination address. SO_LINGER controls the action taken when unsent messags are queued on socket and a CloseSocket() is performed. If the socket promises reliable delivery of data and SO_LINGER is set, the system will block the process on the close attempt until it is able to transmit the data or until it decides it is unable to deliver the information (a timeout period, in seconds, termed the linger interval, is specified in the set- sockopt() call when SO_LINGER is requested). If SO_LINGER is disabled and a CloseSocket() is issued, the system will process the close in a manner that allows the process to continue as quickly as possible. The option SO_BROADCAST requests permission to send broad- cast datagrams on the socket. Broadcast was a privileged operation in earlier versions of the system. With protocols that support out-of-band data, the SO_OOBINLINE option requests that out-of-band data be placed in the normal data input queue as received; it will then be accessible with recv() or read() calls without the MSG_OOB flag. SO_SNDBUF and SO_RCVBUF are options to adjust the normal buffer sizes allocated for output and input buffers, respectively. The buffer size may be increased for high-volume connections, or may be decreased to limit the possible backlog of incoming data. The system places an absolute limit on these values. Finally, SO_TYPE and SO_ERROR are options used only with getsockopt(). SO_TYPE returns the type of the socket, such as SOCK_STREAM; it is useful for servers that inherit sock- ets on startup. SO_ERROR returns any pending error on the socket and clears the error status. It may be used to check for asynchronous errors on connected datagram sockets or for other asynchronous errors. RETURN VALUES 0 - on success. -1 - on failure and set errno to indicate the error. ERRORS EBADF - s is not a valid descriptor. ENOPROTOOPT - The option is unknown at the level indi- cated. SEE ALSO IoctlSocket(), socket() BUGS Several of the socket options should be handled at lower levels of the system. bsdsocket.library/inet_addr bsdsocket.library/inet_addr NAME inet_addr, inet_network, Inet_MakeAddr, Inet_LnaOf, Inet_NetOf, Inet_NtoA - Internet address manipulation inet_makeaddr, inet_lnaof, inet_netof, inet_ntoa -- inline/stub functions to handle structure arguments SYNOPSIS #include <netinet/in.h> addr = inet_addr(cp) D0 A0 unsigned long inet_addr(char *); net = inet_network(cp) D0 A0 unsigned long inet_network(char *); in_addr = Inet_MakeAddr(net, lna) D0 D0 D1 unsigned long Inet_MakeAddr(long, long); lna = Inet_LnaOf(in) D0 D0 long Inet_LnaOf(unsigned long); net = Inet_NetOf(in) D0 D0 long Inet_NetOf(unsigned long); addr = Inet_NtoA(in) DO D0 char * Inet_NtoA(unsigned long); in_addr = inet_makeaddr(net, lna) struct in_addr inet_makeaddr(long, long); lna = inet_lnaof(in) int inet_lnaof(struct in_addr); net = inet_netof(in) int inet_netof(struct in_addr); addr = inet_ntoa(in) char * inet_ntoa(struct in_addr); IMPLEMENTATION NOTE Return value of Inet_MakeAddr() and argument types of Inet_LnaOf(), Inet_NetOf() and Inet_NtoA() are longs instead of struct in_addr. The original behaviour is achieved by using included stub functions (lower case function names) which handle structure arguments. DESCRIPTION The routines inet_addr() and inet_network() each interpret character strings representing numbers expressed in the Internet standard `.' notation, returning numbers suitable for use as Internet addresses and Internet network numbers, respectively. The routine inet_makeaddr() takes an Internet network number and a local network address and constructs an Internet address from it. The routines inet_netof() and inet_lnaof() break apart Internet host addresses, returning the network number and local network address part, respec- tively. The routine inet_ntoa() returns a pointer to a string in the base 256 notation ``d.d.d.d'' described below. All Internet address are returned in network order (bytes ordered from left to right). All network numbers and local address parts are returned as machine format integer values. INTERNET ADDRESSES Values specified using the `.' notation take one of the following forms: a.b.c.d a.b.c a.b a When four parts are specified, each is interpreted as a byte of data and assigned, from left to right, to the four bytes of an Internet address. Note: when an Internet address is viewed as a 32-bit integer quantity on little endian systems, the bytes referred to above appear as d.c.b.a. bytes are ordered from right to left. When a three part address is specified, the last part is interpreted as a 16-bit quantity and placed in the right most two bytes of the network address. This makes the three part address format convenient for specifying Class B net- work addresses as "128.net.host". When a two part address is supplied, the last part is inter- preted as a 24-bit quantity and placed in the right most three bytes of the network address. This makes the two part address format convenient for specifying Class A network addresses as "net.host". When only one part is given, the value is stored directly in the network address without any byte rearrangement. All numbers supplied as ``parts'' in a `.' notation may be decimal, octal, or hexadecimal, as specified in the C language (that is, a leading 0x or 0X implies hexadecimal; otherwise, a leading 0 implies octal; otherwise, the number is interpreted as decimal). RETURN VALUE The value -1 is returned by inet_addr() and inet_network() for malformed requests. BUGS The problem of host byte ordering versus network byte order- ing is confusing. A simple way to specify Class C network addresses in a manner similar to that for Class B and Class A is needed. The return value from inet_ntoa() points to static buffer which is overwritten in each inet_ntoa() call. bsdsocket.library/Inet_LnaOf bsdsocket.library/Inet_LnaOf SEE ALSO inet_addr() bsdsocket.library/inet_MakeAddr bsdsocket.library/inet_MakeAddr SEE ALSO inet_addr() bsdsocket.library/Inet_NetOf bsdsocket.library/Inet_NetOf SEE ALSO inet_addr() bsdsocket.library/inet_network bsdsocket.library/inet_network SEE ALSO inet_addr() bsdsocket.library/Inet_NtoA bsdsocket.library/Inet_NtoA SEE ALSO inet_addr() bsdsocket.library/IoctlSocket bsdsocket.library/IoctlSocket NAME IoctlSocket - control sockets SYNOPSIS #include <sys/types.h> #include <sys/ioctl.h> value = IoctlSocket(fd, request, arg) D0 D0 D1 A0 long IoctlSocket(long, long, caddr_t); FUNCTION IoctlSocket() performs a special function on the object referred to by the open socket descriptor fd. Note: the setsockopt() call (see getsockopt()) is the primary method for operating on sockets as such, rather than on the underlying protocol or network interface. For most IoctlSocket() functions, arg is a pointer to data to be used by the function or to be filled in by the function. Other functions may ignore arg or may treat it directly as a data item; they may, for example, be passed an int value. The following requests are supported: FIOASYNC The argument is a pointer to a long. Set or clear asynchronous I/O. If the value of that long is a 1 (one) the descriptor is set for asynchronous I/O. If the value of that long is a 0 (zero) the descriptor is cleared for asynchro- nous I/O. FIOCLEX FIONCLEX Ignored, no use for close-on-exec flag in Amiga. FIOGETOWN SIOCGPGRP The argument is pointer to struct Task*. Set the value of that pointer to the Task that is receiving SIGIO or SIGURG signals for the socket referred to by the descriptor passed to IoctlSocket(). FIONBIO The argument is a pointer to a long. Set or clear non-blocking I/O. If the value of that long is a 1 (one) the descriptor is set for non-blocking I/O. If the value of that long is a 0 (zero) the descriptor is cleared for non- blocking I/O. FIONREAD The argument is a pointer to a long. Set the value of that long to the number of immediately readable characters from the socket fd. FIOSETOWN SIOCSPGRP The argument is pointer to struct Task*, pointer to the task that will subseq- uently receive SIGIO or SIGURG signals for the socket referred to by the descriptor passed. SIOCCATMARK The argument is a pointer to a long. Set the value of that long to 1 if the read pointer for the socket referred to by the descriptor passed to IoctlSocket() points to a mark in the data stream for an out-of-band message, and to 0 if it does not point to a mark. RETURN VALUES IoctlSocket() returns 0 on success for most requests. Some specialized requests may return non-zero values on success; On failure, IoctlSocket() returns -1 and sets errno to indicate the error. ERRORS EBADF fd is not a valid descriptor. EINVAL request or arg is not valid. IoctlSocket() will also fail if the object on which the function is being performed detects an error. In this case, an error code specific to the object and the function will be returned. SEE ALSO getsockopt(), SocketBaseTagList(), setsockopt() bsdsocket.library/listen bsdsocket.library/listen NAME listen - listen for connections on a socket SYNOPSIS success = listen(s, backlog) D0 D0 D1 long listen(long, long); FUNCTION To accept connections, a socket is first created with socket(), a backlog for incoming connections is specified with listen() and then the connections are accepted with accept(). The listen() call applies only to socket of type SOCK_STREAM. The backlog parameter defines the maximum length the queue of pending connections may grow to. If a connection request arrives with the queue full the client will receive an error with an indication of ECONNREFUSED. RETURN VALUES 0 on success. -1 on failure and sets errno to indicate the error. ERRORS EBADF - s is not a valid descriptor. EOPNOTSUPP - The socket is not of a type that sup- ports listen(). SEE ALSO accept(), connect(), socket() BUGS The backlog is currently limited (silently) to 5. bsdsocket.library/ObtainSocket bsdsocket.library/ObtainSocket NAME ObtainSocket - get a socket from AmiTCP/IP socket list SYNOPSIS s = ObtainSocket(id, domain, type, protocol) D0 D0 D1 D2 D3 LONG ObtainSocket(LONG, LONG, LONG, LONG); FUNCTION When one task wants to give a socket to an another one, it releases it (with a key value) to a special socket list held by AmiTCP/IP. This function requests that socket and receives it if id and other parameters match. INPUTS id - a key value given by the socket donator. domain - see documentation of socket(). type - see documentation of socket(). protocol - see documentation of socket(). RESULT Non negative socket descriptor on success. On failure, -1 is returned and the errno is set to indicate the error. ERRORS EMFILE - The per-process descriptor table is full. EPROTONOSUPPORT - The protocol type or the specified pro- tocol is not supported within this domain. EPROTOTYPE - The protocol is the wrong type for the socket. EWOULDBLOCK - Matching socket is not found. SEE ALSO ReleaseCopyOfSocket(), ReleaseSocket(), socket() bsdsocket.library/recv bsdsocket.library/recv NAME recv, recvfrom, - receive a message from a socket SYNOPSIS #include <sys/types.h> #include <sys/socket.h> nbytes = recv(s, buf, len, flags) D0 D0 A0 D1 D2 long recv(long, char *, long, long); nbytes = recvfrom(s, buf, len, flags, from, fromlen) D0 D0 A0 D1 D2 A1 A2 long recvfrom(long, char *, long, long, struct sockaddr *, long *); FUNCTION s is a socket created with socket(). recv() and recvfrom(), are used to receive messages from another socket. recv() may be used only on a connected socket (see connect()), while recvfrom() may be used to receive data on a socket whether it is in a connected state or not. If from is not a NULL pointer, the source address of the message is filled in. fromlen is a value-result parameter, initialized to the size of the buffer associated with from, and modified on return to indicate the actual size of the address stored there. The length of the message is returned. If a message is too long to fit in the supplied buffer, excess bytes may be discarded depending on the type of socket the message is received from (see socket()). If no messages are available at the socket, the receive call waits for a message to arrive, unless the socket is non- blocking (see IoctlSocket()) in which case -1 is returned with the external variable errno set to EWOULDBLOCK. The select() call may be used to determine when more data arrive. The flags parameter is formed by ORing one or more of the following: MSG_OOB - Read any "out-of-band" data present on the socket, rather than the regular "in-band" data. MSG_PEEK - "Peek" at the data present on the socket; the data are returned, but not consumed, so that a subsequent receive operation will see the same data. RETURN VALUES These calls return the number of bytes received, or -1 if an error occurred. ERRORS EBADF - s is an invalid descriptor. EINTR - The operation was interrupted by a break signal. EWOULDBLOCK - The socket is marked non-blocking and the requested operation would block. SEE ALSO connect(), getsockopt(), IoctlSocket(), select(), send(), SocketBaseTagList(), socket() bsdsocket.library/recvfrom bsdsocket.library/recvfrom SEE ALSO recv() bsdsocket.library/ReleaseCopyOfSocket bsdsocket.library/ReleaseCopyOfSocket NAME ReleaseCopyOfSocket - copy given socket to AmiTCP/IP socket list. SYNOPSIS id = ReleaseCopyOfSocket(fd, id) D0 D0 D1 LONG ReleaseCopyOfSocket(LONG, LONG); FUNCTION Make a new reference to a given socket (pointed by its descriptor) and release it to the socket list held by AmiTCP/IP. INPUTS fd - descriptor of the socket to release. id - the key value to identify use of this socket. It can be unique or not, depending on its value. If id value is between 0 and 65535, inclusively, it is considered nonunique and it can be used as a port number, for example. If id is greater than 65535 and less than 2^31) it must be unique in currently held sockets in AmiTCP/IP socket list, Otherwise an error will be returned and socket is not released. If id == UNIQUE_ID (defined in <sys/socket.h>) an unique id will be generated. RESULT id - -1 in case of error and the key value of the socket put in the list. Most useful when an unique id is generated by this routine. ERRORS EINVAL - Requested unique id is already used. ENOMEM - Needed memory couldn't be allocated. NOTE The socket descriptor is not deallocated. SEE ALSO ObtainSocket(), ReleaseSocket() bsdsocket.library/ReleaseSocket bsdsocket.library/ReleaseSocket NAME ReleaseSocket - release given socket to AmiTCP/IP socket list. SYNOPSIS id = ReleaseSocket(fd, id) D0 D0 D1 LONG ReleaseSocket(LONG, LONG); FUNCTION Release the reference of given socket (via its descriptor) and move the socket to the socket list held by AmiTCP/IP. The socket descriptor is deallocated in this procedure. INPUTS fd - descriptor of the socket to release. id - the key value to identify use of this socket. It can be unique or not, depending on its value. If id value is between 0 and 65535, inclusively, it is considered nonunique and it can be used as a port number, for example. If id is greater than 65535 and less than 2^31) it must be unique in currently held sockets in AmiTCP/IP socket list, Otherwise an error will be returned and socket is not released. If id == UNIQUE_ID (defined in <sys/socket.h>) an unique id will be generated. RESULT id - -1 in case of error and the key value of the socket put in the list. Most useful when an unique id is generated by this routine. ERRORS EINVAL - Requested unique id is already used. ENOMEM - Needed memory couldn't be allocated. SEE ALSO ObtainSocket(), ReleaseCopyOfSocket() bsdsocket.library/select bsdsocket.library/select NAME select -- synchronous I/O multiplexing (stub/inline function) WaitSelect -- select() with Amiga Wait() function. SYNOPSIS #include <sys/types.h> #include <sys/time.h> n = select (nfds, readfds, writefds, exceptfds, timeout) long select(long, fd_set *, fd_set *, fd_set *, struct timeval *); n = WaitSelect (nfds, readfds, writefds, exceptfds, timeout, D0 D0 A0 A1 A2 A3 sigmp) D1 long WaitSelect(long, fd_set *, fd_set *, fd_set *, struct timeval *, long *); FD_SET (fd, &fdset) FD_CLR (fd, &fdset) FD_ISSET (fd, &fdset) FD_ZERO (&fdset) long fd; fd_set fdset; DESCRIPTION select() examines the socket descriptor sets whose addresses are passed in readfds, writefds, and exceptfds to see if some of their descriptors are ready for reading, ready for writing, or have an exceptional condition pending. nfds is the number of bits to be checked in each bit mask that represent a file descriptor; the descriptors from 0 through (nfds - 1) in the descriptor sets are examined. On return, select() replaces the given descriptor sets with subsets consisting of those descriptors that are ready for the requested operation. The total number of ready descriptors in all the sets is returned. WaitSelect() also takes a signal mask which is waited during normal select() operation. If one of these singals is recei- ved, WaitSelect() returns and has re-set the signal mask to return those signals that have arrived. Normal select() return values are returned. The descriptor sets are stored as bit fields in arrays of integers. The following macros are provided for manipulat- ing such descriptor sets: FD_ZERO (&fdset) initializes a descriptor set fdset to the null set. FD_SET(fd, &fdset ) includes a particular descriptor fd in fdset. FD_CLR(fd, &fdset) removes fd from fdset. FD_ISSET(fd, &fdset) is nonzero if fd is a member of fdset, zero otherwise. The behavior of these macros is undefined if a descriptor value is less than zero or greater than or equal to FD_SETSIZE, which is normally at least equal to the maximum number of descriptors supported by the system. If timeout is not a NULL pointer, it specifies a maximum interval to wait for the selection to complete. If timeout is a NULL pointer, the select blocks indefinitely. To effect a poll, the timeout argument should be a non-NULL pointer, pointing to a zero-valued timeval structure. Any of readfds, writefds, and exceptfds may be given as NULL pointers if no descriptors are of interest. Selecting true for reading on a socket descriptor upon which a listen() call has been performed indicates that a subse- quent accept() call on that descriptor will not block. RETURN VALUES select() returns a non-negative value on success. A positive value indicates the number of ready descriptors in the descriptor sets. 0 indicates that the time limit referred to by timeout expired or that the operation was interrupted either by a break signal or by arrival of a signal specified in *sigmp. On failure, select() returns -1, sets errno to indicate the error, and the descriptor sets are not changed. ERRORS EBADF - One of the descriptor sets specified an invalid descriptor. EINTR - one of the signals in SIGINTR mask (see Set- SocketSignals()) is set and it was not requested in WaitSelect() call. EINVAL - A component of the pointed-to time limit is outside the acceptable range: t_sec must be between 0 and 10^8, inclusive. t_usec must be greater than or equal to 0, and less than 10^6. SEE ALSO accept(), connect(), getdtablesize(), listen(), recv(), send(), SetDTableSize(), SetSocketSignals() NOTES Under rare circumstances, select() may indicate that a descriptor is ready for writing when in fact an attempt to write would block. This can happen if system resources necessary for a write are exhausted or otherwise unavail- able. If an application deems it critical that writes to a file descriptor not block, it should set the descriptor for non-blocking I/O using the FIOASYNC request to IoctlSocket(). Default system limit for open socket descriptors is currently 64. However, in order to accommodate programs which might potentially use a larger number of open files with select, it is possible to increase this size within a program by providing a larger definition of FD_SETSIZE before the inclusion of <sys/types.h> and use SocketBaseTags(SBTM_SETVAL(SBTC_DTABLESIZE), FD_SETSIZE); call directly after OpenLibrary(). BUGS select() should probably return the time remaining from the original timeout, if any, by modifying the time value in place. This may be implemented in future versions of the system. Thus, it is unwise to assume that the timeout pointer will be unmodified by the select() call. bsdsocket.library/send bsdsocket.library/send NAME send, sendto - send a message from a socket SYNOPSIS #include <sys/types.h> #include <sys/socket.h> nbytes = send(s, msg, len, flags) D0 D0 A0 D1 D2 int send(int, char *, int, int); nbytes = sendto(s, msg, len, flags, to, tolen) D0 D0 A0 D1 D2 A1 D3 int send(int, char *, int, int, struct sockaddr *, int); FUNCTION s is a socket created with socket(). send() and sendto() are used to transmit a message to another socket. send() may be used only when the socket is in a connected state, while sendto() may be used at any time. The address of the target is given by to with tolen specify- ing its size. The length of the message is given by len. If the message is too long to pass atomically through the underlying protocol, then the error EMSGSIZE is returned, and the message is not transmitted. No indication of failure to deliver is implicit in a send(). Return values of -1 indicate some locally detected errors. If no buffer space is available at the socket to hold the message to be transmitted, then send() normally blocks, unless the socket has been placed in non-blocking I/O mode. The select() call may be used to determine when it is pos- sible to send more data. The flags parameter is formed by ORing one or more of the following: MSG_OOB - Send ``out-of-band'' data on sockets that support this notion. The underly- ing protocol must also support ``out- of-band'' data. Currently, only SOCK_STREAM sockets created in the AF_INET address family support out-of- band data. MSG_DONTROUTE - The SO_DONTROUTE option is turned on for the duration of the operation. This is usually used only by diagnostic or rout- ing programs. RETURN VALUES On success, these functions return the number of bytes sent. On failure, they return -1 and set errno to indicate the error. ERRORS EBADF - s is an invalid descriptor. EINTR - The operation was interrupted by a break signal. EINVAL - len is not the size of a valid address for the specified address family. EMSGSIZE - The socket requires that message be sent atomically, and the size of the message to be sent made this impossible. ENOBUFS - The system was unable to allocate an internal buffer. The operation may succeed when buffers become available. ENOBUFS - The output queue for a network interface was full. This generally indicates that the interface has stopped sending, but may be caused by transient congestion. EWOULDBLOCK - The socket is marked non-blocking and the requested operation would block. SEE ALSO connect(), getsockopt(), recv(), select(), socket() bsdsocket.library/sendto bsdsocket.library/sendto SEE ALSO send() bsdsocket.library/SetErrnoPtr bsdsocket.library/SetErrnoPtr NAME SetErrnoPtr - set new place where the error value will be written SYNOPSIS SetErrnoPtr(ptr, size) A0 D0 VOID SetErrnoPtr(VOID *, UBYTE); FUNCTION This functions allows caller to redirect error variable inside scope of caller task. Usually this is used to make task's global variable errno as error variable. INPUTS ptr - pointer to error variable that is to be modified on every error condition on this library function. size - size of the error variable. EXAMPLE #include <errno.h> struct Library; struct Library * SocketBase = NULL; int main(void) { ... if ((SocketBase = OpenLibrary("bsdsocket.library", 2)) != NULL) { SetErrnoPtr(&errno, sizeof(errno)); ... } } NOTES Be sure that this new error variable exists until library base is finally closed or SetErrnoPtr() is called again for another variable. SEE ALSO Errno() bsdsocket.library/SetSocketSignals bsdsocket.library/SetSocketSignals NAME SetSocketSignals - inform AmiTCP/IP of INTR, IO and URG signals SYNOPSIS SetSocketSignals(sigintrmask, sigiomask, sigurgmask) D0 D1 D2 VOID SetSocketSignals(ULONG, ULONG, ULONG); FUNCTION SetSocketSignals() tells the AmiTCP/IP which signal masks corresponds UNIX SIGINT, SIGIO and SIGURG signals to be used in this implementation. The sigintrmask mask is used to determine which Amiga signals interrupt blocking library calls. The sigiomask is sent when asynchronous notification of socket events is done, the sigurgmask is sent when out-of-band data arrives, respectively. The signals are sent only to the owning task of particular socket. The socket has got no owner by default; the owner is set by FIOSETOWN (SIOCSPGRP) ioctl call. Note that the supplied values write over old ones. If this function is used and CTRL-C is still wanted to interrupt the calls (the default behaviour), the value BREAKF_CTRL_C must be explicitly given. NOTES The function SetSocketSignals() is obsoleted by the function SocketBaseTags(). SEE ALSO IoctlSocket(), recv(), send(), select(), WaitSelect() bsdsocket.library/inet_lnaof bsdsocket.library/inet_lnaof SEE ALSO inet_addr() bsdsocket.library/inet_makeaddr bsdsocket.library/inet_makeaddr SEE ALSO inet_addr() bsdsocket.library/inet_netof bsdsocket.library/inet_netof SEE ALSO inet_addr() bsdsocket.library/inet_ntoa bsdsocket.library/inet_ntoa SEE ALSO inet_addr() bsdsocket.library/setsockopt bsdsocket.library/setsockopt SEE ALSO getsockopt() bsdsocket.library/shutdown bsdsocket.library/shutdown NAME shutdown - shut down part of a full-duplex connection SYNOPSIS success = shutdown(s, how) D0 D0 D1 long shutdown(long, long); DESCRIPTION The shutdown() call causes all or part of a full-duplex con- nection on the socket associated with s to be shut down. If how is 0, then further receives will be disallowed. If how is 1, then further sends will be disallowed. If how is 2, then further sends and receives will be disallowed. RETURN VALUES 0 - on success. -1 - on failure and sets errno to indicate the error. ERRORS EBADF - s is not a valid descriptor. ENOTCONN - The specified socket is not connected. SEE ALSO connect(), socket() BUGS The how values should be defined constants. bsdsocket.library/socket bsdsocket.library/socket NAME socket - create an endpoint for communication SYNOPSIS #include <sys/types.h> #include <sys/socket.h> s = socket(domain, type, protocol) D0 D0 D1 D2 long socket(long, long, long); FUNCTION socket() creates an endpoint for communication and returns a descriptor. The domain parameter specifies a communications domain within which communication will take place; this selects the protocol family which should be used. The protocol family generally is the same as the address family for the addresses supplied in later operations on the socket. These families are defined in the include file <sys/socket.h>. The currently understood formats are PF_INET - (ARPA Internet protocols) The socket has the indicated type, which specifies the semantics of communication. Currently defined types are: SOCK_STREAM SOCK_DGRAM SOCK_RAW A SOCK_STREAM type provides sequenced, reliable, two-way connection based byte streams. An out-of-band data transmission mechanism may be supported. A SOCK_DGRAM socket supports datagrams (connectionless, unreliable mes- sages of a fixed (typically small) maximum length). SOCK_RAW sockets provide access to internal network interfaces. The protocol specifies a particular protocol to be used with the socket. Normally only a single protocol exists to sup- port a particular socket type within a given protocol fam- ily. However, it is possible that many protocols may exist, in which case a particular protocol must be specified in this manner. The protocol number to use is particular to the "communication domain" in which communication is to take place. Sockets of type SOCK_STREAM are full-duplex byte streams, similar to pipes. A stream socket must be in a connected state before any data may be sent or received on it. A con- nection to another socket is created with a connect() call. Once connected, data may be transferred using send() and recv() or their variant calls. When a session has been completed a CloseSocket() may be performed. Out-of-band data may also be transmitted as described in send() and received as described in recv(). The communications protocols used to implement a SOCK_STREAM insure that data is not lost or duplicated. If a piece of data for which the peer protocol has buffer space cannot be successfully transmitted within a reasonable length of time, then the connection is considered broken and calls will indicate an error with -1 returns and with ETIMEDOUT as the specific error code (see Errno()). The protocols optionally keep sockets "warm" by forcing transmissions roughly every minute in the absence of other activity. SOCK_DGRAM and SOCK_RAW sockets allow sending of datagrams to correspondents named in send() calls. Datagrams are generally received with recv(), which returns the next datagram with its return address. The operation of sockets is controlled by socket level options. These options are defined in the file socket.h. getsockopt() and setsockopt() are used to get and set options, respectively. RETURN VALUES socket() returns a non-negative descriptor on success. On failure, it returns -1 and sets errno to indicate the error. ERRORS EACCES - Permission to create a socket of the specified type and/or protocol is denied. EMFILE - The per-process descriptor table is full. ENOBUFS - Insufficient buffer space is available. The socket cannot be created until suf- ficient resources are freed. EPROTONOSUPPORT - The protocol type or the specified pro- tocol is not supported within this domain. EPROTOTYPE - The protocol is the wrong type for the socket. SEE ALSO accept(), bind(), CloseSocket(), connect(), getsockname(), getsockopt(), IoctlSocket(), listen(), recv(), select(), send(), shutdown(), WaitSelect() bsdsocket.library/SocketBaseTagList bsdsocket.library/SocketBaseTagList NAME SocketBaseTagList - Set/Get SocketBase attributes. SYNOPSIS #include <amitcp/socketbasetags.h> ULONG SocketBaseTagList(struct TagItem *); error = SocketBaseTagList(taglist) D0 A0 error = SocketBaseTags(ULONG tag, ...); FUNCTION Set or get a list of (mostly) SocketBase instance dependent attributes from the AmiTCP. INPUTS These functions expect as their argument a standard tag list, one or several array of struct TagItem as defined in the header file <utility/tagitem.h>. The structure contains two fields: ti_Tag and ti_Data. The ti_Tag field contains tag code, which determines what the SocketBaseTagList() should do with its argument, the ti_Data field. The include file <amitcp/socketbasetags.h> defines macros for base tag code values. Base tag code macros begin with `SBTC_' (as Socket Base Tag Code). The base tag value defines what data item the tag item refers. The tag code contains other information besides the referred data item. It controls, whether the SocketBaseTagList() should set or get the appropriate parameter, and whether the argument of the tag in question is passed by value or by reference. The include file <amitcp/socketbasetags.h> defines the following macros, which are used to construct the ti_Tag values from the base tag codes: SBTM_GETREF(code) - get by reference SBTM_GETVAL(code) - get by value SBTM_SETREF(code) - set by reference SBTM_SETVAL(code) - set by value If the actual data is stored directly into the ti_Data field, you should use the 'by value' macros, SBTM_GETVAL() or SBTM_SETVAL(). However, if the ti_Data field contains a pointer to actual data, you should use the 'by reference' macros, SBTM_GETREF() or SBTM_SETREF(). In either case the actual data should always be a LONG aligned to even address. According the used tag naming scheme a tag which has "PTR" suffix takes an pointer as its argument. Don't mix the pointer arguments with 'by reference' argument passing. It is possible to pass a pointer by reference (in which case the ti_Data is a pointer to the actual pointer). The list of all defined base tag codes is as follows: SBTC_BREAKMASK Tag data contains the INTR signal mask. If the calling task receives a signal in the INTR mask, the AmiTCP interrupts current function calls and returns with the error code EINTR. The INTR mask defaults to the CTRL-C signal (SIGBREAKF_C, bit 12). SBTC_DTABLESIZE Socket Descriptor Table size. This defaults to 64. SBTC_ERRNO The errno value. The values are defined in <sys/errno.h>. SBTC_ERRNOBYTEPTR SBTC_ERRNOWORDPTR SBTC_ERRNOLONGPTR SBTC_ERRNOPTR(size) Set (only) the pointer to the errno variable defined by the program. AmiTCP defines a value for this by default, but the application must set the pointer (and the size of the errno) with one of these tags, if it wishes to access the errno variable directly. The SBTC_ERRNOPTR(size) is a macro, which expands to one of the other (BYTE, WORD or LONG) tag codes, meaning that only 1, 2 and 4 are legal size values. The netlib autoinit.c sets the errno pointer for the application, if the application is linked with it. SBTC_ERRNOSTRPTR Returns an error string pointer describing the errno value given on input. You can not set the error message, only get is allowed. On call the ti_Data must contain the error code number. On return the ti_Data is assigned to the string pointer. (*ti_Data, if passed by reference). See the file <sys/errno.h> for symbolic definitions for the errno codes. SBTC_FDCALLBACK A callback function pointer for coordination of file descriptor usage between AmiTCP and link-library. By default no callback is called and the value of this pointer is NULL. The prototype for the callback function is: int error = fdCallback(int fd, int action); D0 D0 D1 where error - 0 for success or one of the error codes in <sys/errno.h> in case of error. The AmiTCP API function that calls the callback usually returns the 'error' back to the caller without any further modification. fd - file descriptor number to take 'action' on. action - one of the following actions (defined in <amitcp/socketbasetags.h>): FDCB_FREE - mark the 'fd' as unused on the link library structure. If 'fd' represents a file handled by the link library, the error (ENOTSOCK) should be returned. FDCB_ALLOC - mark the 'fd' allocated as a socket. FDCB_CHECK - check if the 'fd' is free. If an error is returned, the 'fd' is marked as used in the AmiTCP/IP structures. The AmiTCP/IP calls the callback every time a socket descriptor is allocated or freed. AmiTCP/IP uses the FDCB_CHECK before actual allocation to check that it agrees with the link library on the next free descriptor number. Thus the link library doesn't need to tell the AmiTCP if it creates a new file handle in open(), for example. See file _chkufb.c on the net.lib sources for an example implementation of the callback function for the SAS/C. SBTC_HERRNO The name resolver error code value. Get this to find out why the gethostbyname() or gethostbyaddr() failed. The values are defined in <netdb.h> SBTC_HERRNOSTRPTR Returns host error string for error number in tag data. Host error is set on unsuccesful gethostbyname() and gethostbyaddr() calls. See the file <netdb.h> for the symbolic definitions for the herrno valus. Notes for the SBTC_ERRNOSTRPTR apply also to this tag code. SBTC_IOERRNOSTRPTR Returns an error string for standard AmigaOS I/O error number as defined in the header file <exec/errors.h>. Note that the error number taken by this tag code is positive, so the error codes must be negated (to be positive). The positive error codes depend on the particular IO device, the standard Sana-II error codes can be retrieved by the tag code SBTC_S2ERRNOSTRPTR. Notes for the SBTC_ERRNOSTRPTR apply also to this tag code. SBTC_LOGFACILITY Facility code for the syslog messages as defined in the header file <sys/syslog.h>. Defaults to LOG_USER. SBTC_LOGMASK Sets the filter mask of the syslog messages. By default the mask is 0xff, meaning that all messages are passed to the log system. SBTC_LOGSTAT Syslog options defined in <sys/syslog.h>. SBTC_LOGTAGPTR A pointer to a string which is used by syslog() to mark individual syslog messages. This defaults to NULL, but is set to the name of the calling program by the autoinit code in netlib:autoinit.c. This is for compatibility with pre-3.0 programs. SBTC_S2ERRNOSTRPTR Returns an error string for a Sana-II specific I/O error code as defined in the header file <devices/sana2.h>. Notes for the SBTC_ERRNOSTRPTR apply also to this tag code. SBTC_S2WERRNOSTRPTR Returns an error string for a Sana-II Wire Error code as defined in the header file <devices/sana2.h>. Notes for the SBTC_ERRNOSTRPTR apply also to this tag code. SBTC_SIGIOMASK The calling task is sent the signals specified by mask in tag data when asynhronous I/O is to be notified. The default value is zero, ie. no signal is sent. SBTC_SIGURGMASK The calling task is sent the signals specified by mask in tag data when urgent data for the TCP arrives. The default value is zero, ie. no signal is sent. RESULT Returns 0 on success, and a (positive) index of the failing tag on error. Note that the value 1 means _first_ TagItem, 2 the second one, and so on. The return value is NOT a C-language index, which are 0 based. EXAMPLES To be written, see net.lib sources for various examples. NOTES BUGS None known. SEE ALSO <netinclude:amitcp/socketbasetags.h>, <include:utility/tagitem.h> bsdsocket.library/syslog bsdsocket.library/syslog NAME syslog, vsyslog - write message to AmiTCP/IP log. SYNOPSIS #include <syslog.h> vsyslog(level, format, ap) D0 A0 A1 void syslog(unsigned long level, char * format, ...); void vsyslog(unsigned long level, char * format, ap); FUNCTION Writes the message given as format string and arguments (printf-style) both to the log file and to the console. The message is prepended with the name of the calling application, if the name is known by AmiTCP (the standard autoinitiazer module in the net.lib passes the name of the application to AmiTCP). The level is selected from an ordered list: LOG_EMERG A panic condition. LOG_ALERT A condition that should be corrected immediately, such as a corrupted system database. LOG_CRIT Critical conditions, such as hard device errors. LOG_ERR Errors. LOG_WARNING Warning messages. LOG_NOTICE Conditions that are not error con- ditions, but that may require spe- cial handling. LOG_INFO Informational messages. LOG_DEBUG Messages that contain information normally of use only when debugging a program. INPUTS Level - indicates the type of the message. The levels are defined in sys/syslog.h and listed above. format - This is a printf-style format string. arguments - as in printf(). ap - pointer to an array of arguments. RESULT Returns no value. EXAMPLES To log a message at priority LOG_INFO, it would make the following call to syslog: syslog(LOG_INFO, "Connection from host %s", CallingHost); NOTES In contrast to the previous releases of the AmiTCP/IP, the integer arguments are expected to be 32 bits wide, thus eliminating the need to specify the 'l' size modifier for the number formatters. This function is callable from interrupts. BUGS Because there is a limited number of internal messages used by the logging system, some log messages may get lost if a high priority task or interrupt handler sends many messages in succession. If this happens, the next log message tells the fact. SEE ALSO net.lib/syslog for syslog utility functions (openlog(), closelog() and setlogmask()), C-library printf() documentation protocols/arp protocols/arp NAME arp - Address Resolution Protocol CONFIG Any SANA-II device driver using ARP SYNOPSIS #include <sys/socket.h> #include <net/if_arp.h> #include <netinet/in.h> s = socket(AF_INET, SOCK_DGRAM, 0); DESCRIPTION ARP is a protocol used to dynamically map between Internet Protocol (IP) and hardware addresses. It can be used by most the SANA-II network interface drivers. The current implementation supports only Internet Protocol (and is tested only with Ethernet). However, ARP is not limited to only that combination. ARP caches IP-to-hardware address mappings. When an interface requests a mapping for an address not in the cache, ARP queues the message which requires the mapping and broadcasts a message on the associated network requesting the address mapping. If a response is provided, the new mapping is cached and any pending message is transmitted. ARP will queue at most one packet while waiting for a mapping request to be responded to; only the most recently transmitted packet is kept. The address mapping caches are separate for each interface. The amount of mappings in the cache may be specified with an IoctlSocket() request. To facilitate communications with systems which do not use ARP, IoctlSocket() requests are provided to enter and delete entries in the IP-to-Ethernet tables. USAGE #include <sys/ioctl.h> #include <sys/socket.h> #include <net/if.h> #include <net/if_arp.h> struct arpreq arpreq; IoctlSocket(s, SIOCSARP, (caddr_t)&arpreq); IoctlSocket(s, SIOCGARP, (caddr_t)&arpreq); IoctlSocket(s, SIOCDARP, (caddr_t)&arpreq); These three IoctlSocket()s take the same structure as an argument. SIOCSARP sets an ARP entry, SIOCGARP gets an ARP entry, and SIOCDARP deletes an ARP entry. These IoctlSocket() requests may be applied to any socket descriptor (s). The arpreq structure contains: /* Maximum number of octets in protocol/hw address */ #define MAXADDRARP 16 /* * ARP ioctl request. */ struct arpreq { struct sockaddr arp_pa; /* protocol address */ struct { /* hardware address */ u_char sa_len; /* actual length + 2 */ u_char sa_family; char sa_data[MAXADDRARP]; } arp_ha; int arp_flags; /* flags */ }; /* arp_flags and at_flags field values */ #define ATF_INUSE 0x01 /* entry in use */ #define ATF_COM 0x02 /* completed entry */ #define ATF_PERM 0x04 /* permanent entry */ #define ATF_PUBL 0x08 /* publish entry */ The interface whose ARP table is manipulated is specified by arp_pa sockaddr. The address family for the arp_pa sockaddr must be AF_INET; for the arp_ha sockaddr it must be AF_UNSPEC. The length of arp_ha must match the length of used hardware address. Maximum length for the hardware address is MAXADDRARP bytes. The only flag bits which may be written are ATF_PERM and ATF_PUBL. ATF_PERM makes the entry permanent if the IoctlSocket() call succeeds. ATF_PUBL specifies that the ARP code should respond to ARP requests for the indicated host coming from other machines. This allows a host to act as an ARP server which may be useful in convincing an ARP-only machine to talk to a non-ARP machine. UNSUPPORTED IN AmiTCP/IP AmiTCP/IP EXTENSIONS There is an extension to the standard BSD4.4 ARP ioctl interface to access the contents of the whole ARP mapping cache. (In the BSD4.4 the static ARP table is accessed via the /dev/kmem.) The SIOCGARPT ioctl takes the following arptabreq structure as an argument: /* * An AmiTCP/IP specific ARP table ioctl request */ struct arptabreq { struct arpreq atr_arpreq; /* To identify the interface */ long atr_size; /* # of elements in atr_table */ long atr_inuse; /* # of elements in use */ struct arpreq *atr_table; }; The atr_arpreq specifies the used interface. The hardware address for the interface is returned in the arp_ha field of atr_arpreq structure. The SIOCGARPT ioctl reads at most atr_size entries from the cache into the user supplied buffer atr_table, if it is not NULL. Actual amount of returned entries is returned in atr_size. The current amount of cached mappings is returned in the atr_inuse. The SIOCGARPT ioctl has following usage: struct arpreq cache[N]; struct arptabreq arptab = { N, 0, cache }; IoctlSocket(s, SIOCGARPT, (caddr_t)&arptabreq); DIAGNOSTICS ARP watches passively for hosts impersonating the local host (that is, a host which responds to an ARP mapping request for the local host's address). "duplicate IP address a.b.c.d!!" "sent from hardware address: %x:%x:...:%x:%x" ARP has discovered another host on the local network which responds to mapping requests for its own Internet address. BUGS The ARP is tested only with Ethernet. Other network hardware may require special ifconfig configuration. SEE ALSO inet, netutil/arp, netutil/ifconfig, <net/if_arp.h> Plummer, Dave, ``An Ethernet Address Resolution Protocol -or- Converting Network Protocol Addresses to 48.bit Ether- net Addresses for Transmission on Ethernet Hardware,'' RFC 826, Network Information Center, SRI International, Menlo Park, Calif., November 1982. (Sun 800-1059-10) protocols/icmp protocols/icmp NAME icmp - Internet Control Message Protocol SYNOPSIS #include <sys/socket.h> #include <netinet/in.h> int socket(AF_INET, SOCK_RAW, proto) DESCRIPTION ICMP is the error and control message protocol used by IP and the Internet protocol family. It may be accessed through a ``raw socket'' for network monitoring and diagnostic functions. The proto parameter to the socket call to create an ICMP socket is obtained from getprotobyname(). ICMP sockets are connectionless, and are normally used with the sendto() and recvfrom() calls, though the connect() call may also be used to fix the destination for future packets (in which case the recv() and send() socket library calls may be used). Outgoing packets automatically have an IP header prepended to them (based on the destination address). Incoming packets are received with the IP header and options intact. DIAGNOSTICS A socket operation may fail with one of the following errors returned: [EISCONN] when trying to establish a connection on a socket which already has one, or when trying to send a datagram with the destination address specified and the socket is already connected; [ENOTCONN] when trying to send a datagram, but no destination address is specified, and the socket hasn't been connected; [ENOBUFS] when the system runs out of memory for an internal data structure; [EADDRNOTAVAIL] when an attempt is made to create a socket with a network address for which no network interface exists. SEE ALSO bsdsocket.library/send(), bsdsocket.library/recv(), inet, ip HISTORY The icmp protocol is originally from 4.3BSD. protocols/if protocols/if NAME if - Network Interface to SANA-II devices DESCRIPTION Each network interface in the AmiTCP/IP corresponds to a path through which messages may be sent and received. A network interface usually has a SANA-II device driver associated with it, though the loopback interface, "lo", do not. The network interface in the AmiTCP/IP (sana_softc) is superset of the BSD Unix network interface. When the network interface is first time referenced, AmiTCP/IP tries to open the corresponding SANA-II device driver. If successful, a software interface to the SANA-II device is created. The "network/" prefix is added to the SANA-II device name, if needed. Once the interface has acquired its address, it is expected to install a routing table entry so that messages can be routed through it. The SANA-II interfaces must be configured before they will allow traffic to flow through them. It is done after the interface is assigned a protocol address with a SIOCSIFADDR ioctl. Some interfaces may use the protocol address or a part of it as their hardware address. On interfaces where the network-link layer address mapping is static, only the network number is taken from the ioctl; the remainder is found in a hardware specific manner. On interfaces which provide dynamic network-link layer address mapping facilities (for example, Ethernets or Arcnets using ARP), the entire address specified in the ioctl is used. The following ioctl calls may be used to manipulate network interfaces. Unless specified otherwise, the request takes an ifreq structure as its parameter. This structure has the form struct ifreq { char ifr_name[IFNAMSIZ]; /* interface name (eg. "slip.device/0")*/ union { struct sockaddr ifru_addr; struct sockaddr ifru_dstaddr; short ifru_flags; } ifr_ifru; #define ifr_addr ifr_ifru.ifru_addr /* address */ #define ifr_dstaddr ifr_ifru.ifru_dstaddr /* end of p-to-p link */ #define ifr_flags ifr_ifru.ifru_flags /* flags */ }; SIOCSIFADDR Set interface address. Following the address assignment, the ``initialization'' routine for the interface is called. SIOCGIFADDR Get interface address. SIOCSIFDSTADDR Set point to point address for interface. SIOCGIFDSTADDR Get point to point address for interface. SIOCSIFFLAGS Set interface flags field. If the interface is marked down, any processes currently routing packets through the interface are notified. SIOCGIFFLAGS Get interface flags. SIOCGIFCONF Get interface configuration list. This request takes an ifconf structure (see below) as a value-result parameter. The ifc_len field should be initially set to the size of the buffer pointed to by ifc_buf. On return it will contain the length, in bytes, of the configuration list. /* * Structure used in SIOCGIFCONF request. * Used to retrieve interface configuration * for machine (useful for programs which * must know all networks accessible). */ struct ifconf { int ifc_len; /* size of associated buffer */ union { caddr_t ifcu_buf; struct ifreq *ifcu_req; } ifc_ifcu; #define ifc_buf ifc_ifcu.ifcu_buf /* buffer address */ #define ifc_req ifc_ifcu.ifcu_req /* array of structures returned */ }; UNSUPPORTED IN AmiTCP/IP These standard BSD ioctl codes are not currently supported: SIOCADDMULTI Enable a multicast address for the interface. SIOCDELMULTI Disable a previously set multicast address. SIOCSPROMISC Toggle promiscuous mode. AmiTCP/IP EXTENSIONS The following ioctls are used to configure protocol and hardware specific properties of a sana_softc interface. They are used in the AmiTCP/IP only. SIOCSSANATAGS Set SANA-II specific properties with a tag list. SIOCGSANATAGS Get SANA-II specific properties into a wiretype_parameters structure and a user tag list. struct wiretype_parameters { ULONG wiretype; /* the wiretype of the interface */ WORD flags; /* iff_flags */ struct TagItem *tags; /* tag list user provides */ }; SEE ALSO arp, lo, netutil/arp, netutil/ifconfig, <sys/ioctl.h>, <net/if.h>, <net/sana2tags.h> protocols/inet protocols/inet NAME inet - Internet protocol family SYNOPSIS #include <sys/types.h> #include <netinet/in.h> DESCRIPTION The Internet protocol family implements a collection of protocols which are centered around the Internet Protocol (IP) and which share a common address format. The Internet family provides protocol support for the SOCK_STREAM, SOCK_DGRAM, and SOCK_RAW socket types. PROTOCOLS The Internet protocol family is comprised of the Internet Protocol (IP), the Address Resolution Protocol (ARP), the Internet Control Message Protocol (ICMP), the Transmission Control Protocol (TCP), and the User Datagram Protocol (UDP). TCP is used to support the SOCK_STREAM abstraction while UDP is used to support the SOCK_DGRAM abstraction; (SEE ALSO tcp, SEE ALSO udp). A raw interface to IP is available by creating an Internet socket of type SOCK_RAW; (SEE ALSO ip). ICMP is used by the kernel to handle and report errors in protocol processing. It is also accessible to user programs; (SEE ALSO icmp). ARP is used to translate 32-bit IP addresses into varying length hardware addresses; (SEE ALSO arp). The 32-bit IP address is divided into network number and host number parts. It is frequency-encoded; the most significant bit is zero in Class A addresses, in which the high-order 8 bits are the network number. Class B addresses have their high order two bits set to 10 and use the highorder 16 bits as the network number field. Class C addresses have a 24-bit network number part of which the high order three bits are 110. Sites with a cluster of local networks may chose to use a single network number for the cluster; this is done by using subnet addressing. The local (host) portion of the address is further subdivided into subnet number and host number parts. Within a subnet, each subnet appears to be an individual network; externally, the entire cluster appears to be a single, uniform network requiring only a single routing entry. Subnet addressing is enabled and examined by the following ioctl commands on a datagram socket in the Internet domain; they have the same form as the SIOCIFADDR (SEE ALSO if) command. SIOCSIFNETMASK Set interface network mask. The network mask defines the network part of the address; if it contains more of the address than the address type would indicate, then subnets are in use. SIOCGIFNETMASK Get interface network mask. ADDRESSING IP addresses are four byte quantities, stored in network byte order (the native Amiga byte order) Sockets in the Internet protocol family use the following addressing structure: struct sockaddr_in { short sin_family; u_short sin_port; struct in_addr sin_addr; char sin_zero[8]; }; Functions in bsdsocket.library are provided to manipulate structures of this form. The sin_addr field of the sockaddr_in structure specifies a local or remote IP address. Each network interface has its own unique IP address. The special value INADDR_ANY may be used in this field to effect "wildcard" matching. Given in a bind() call, this value leaves the local IP address of the socket unspecified, so that the socket will receive connections or messages directed at any of the valid IP addresses of the system. This can prove useful when a process neither knows nor cares what the local IP address is or when a process wishes to receive requests using all of its network interfaces. The sockaddr_in structure given in the bind() call must specify an in_addr value of either IPADDR_ANY or one of the system's valid IP addresses. Requests to bind any other address will elicit the error EADDRNOTAVAIL. When a connect() call is made for a socket that has a wildcard local address, the system sets the sin_addr field of the socket to the IP address of the network interface that the packets for that connection are routed via. The sin_port field of the sockaddr_in structure specifies a port number used by TCP or UDP. The local port address specified in a bind() call is restricted to be greater than IPPORT_RESERVED (defined in <netinet/in.h>) unless the creating process is running as the super-user, providing a space of protected port numbers. In addition, the local port address must not be in use by any socket of same address family and type. Requests to bind sockets to port numbers being used by other sockets return the error EADDRINUSE. If the local port address is specified as 0, then the system picks a unique port address greater than IPPORT_RESERVED. A unique local port address is also picked when a socket which is not bound is used in a connect() or send() call. This allows programs which do not care which local port number is used to set up TCP connections by sim- ply calling socket() and then connect(), and to send UDP datagrams with a socket() call followed by a send() call. Although this implementation restricts sockets to unique local port numbers, TCP allows multiple simultaneous connections involving the same local port number so long as the remote IP addresses or port numbers are different for each connection. Programs may explicitly override the socket restriction by setting the SO_REUSEADDR socket option with setsockopt (see getsockopt()). SEE ALSO bsdsocket.library/bind(), bsdsocket.library/connect(), bsdsocket.library/getsockopt(), bsdsocket.library/IoctlSocket(), bsdsocket.library/send(), bsdsocket.library/socket(), bsdsocket.library/gethostent(), bsdsocket.library/getnetent(), bsdsocket.library/getprotoent(), bsdsocket.library/getservent(), bsdsocket.library/inet_addr(), arp, icmp, ip, tcp, udp Network Information Center, DDN Protocol Handbook (3 vols.), Network Information Center, SRI International, Menlo Park, Calif., 1985. A AmiTCP/IP Interprocess Communication Primer WARNING The Internet protocol support is subject to change as the Internet protocols develop. Users should not depend on details of the current implementation, but rather the services exported. protocols/ip protocols/ip NAME ip - Internet Protocol SYNOPSIS #include <sys/socket.h> #include <netinet/in.h> int socket(AF_INET, SOCK_RAW, proto) DESCRIPTION IP is the transport layer protocol used by the Internet protocol family. Options may be set at the IP level when using higher-level protocols that are based on IP (such as TCP and UDP). It may also be accessed through a ``raw socket'' when developing new protocols, or special purpose applica- tions. A single generic option is supported at the IP level, IP_OPTIONS, that may be used to provide IP options to be transmitted in the IP header of each outgoing packet. Options are set with setsockopt() and examined with getsockopt(). The format of IP options to be sent is that specified by the IP protocol specification, with one exception: the list of addresses for Source Route options must include the first-hop gateway at the beginning of the list of gateways. The first-hop gateway address will be extracted from the option list and the size adjusted accordingly before use. IP options may be used with any socket type in the Internet family. Raw IP sockets are connectionless, and are normally used with the sendto and recvfrom calls, though the connect() call may also be used to fix the destination for future packets (in which case the recv() and send() system calls may be used). If proto is 0, the default protocol IPPROTO_RAW is used for outgoing packets, and only incoming packets destined for that protocol are received. If proto is non-zero, that protocol number will be used on outgoing packets and to filter incoming packets. Outgoing packets automatically have an IP header prepended to them (based on the destination address and the protocol number the socket is created with). Incoming packets are received with IP header and options intact. DIAGNOSTICS A socket operation may fail with one of the following errors returned: [EISCONN] when trying to establish a connection on a socket which already has one, or when trying to send a datagram with the destination address specified and the socket is already connected; [ENOTCONN] when trying to send a datagram, but no destination address is specified, and the socket hasn't been connected; [ENOBUFS] when the system runs out of memory for an internal data structure; [EADDRNOTAVAIL] when an attempt is made to create a socket with a network address for which no network interface exists. The following errors specific to IP may occur when setting or getting IP options: [EINVAL] An unknown socket option name was given. [EINVAL] The IP option field was improperly formed; an option field was shorter than the minimum value or longer than the option buffer provided. SEE ALSO bsdsocket.library/getsockopt(), bsdsocket.library/send(), bsdsocket.library/recv(), icmp, inet HISTORY The ip protocol appeared in 4.2BSD. protocols/lo protocols/lo NAME lo - Software Loopback Network Interface SYNOPSIS pseudo-device loop DESCRIPTION The loop interface is a software loopback mechanism which may be used for performance analysis, software testing, and/or local communication. There is no SANA-II interface associated with lo. As with other network interfaces, the loopback interface must have network addresses assigned for each address family with which it is to be used. These addresses may be set or changed with the SIOCSIFADDR ioctl. The loopback interface should be the last interface configured, as protocols may use the order of configuration as an indication of priority. The loopback should never be configured first unless no hardware interfaces exist. DIAGNOSTICS "lo%d: can't handle af%d." The interface was handed a message with ad- dresses formatted in an unsuitable address family; the packet was dropped. SEE ALSO inet, if, netutil/ifconfig BUGS Older BSD Unix systems enabled the loopback interface automatically, using a nonstandard Internet address (127.1). Use of that address is now discouraged; a reserved host address for the local network should be used instead. protocols/routing protocols/routing NAME routing - system supporting for local network packet routing DESCRIPTION The network facilities provided general packet routing, leaving routing table maintenance to applications processes. A simple set of data structures comprise a ``routing table'' used in selecting the appropriate network interface when transmitting packets. This table contains a single entry for each route to a specific network or host. A user process, the routing daemon, maintains this data base with the aid of two socket specific ioctl commands, SIOCADDRT and SIOCDELRT. The commands allow the addition and deletion of a single routing table entry, respectively. Routing table manipulations may only be carried out by super-user. A routing table entry has the following form, as defined in <net/route.h>: struct rtentry { u_long rt_hash; struct sockaddr rt_dst; struct sockaddr rt_gateway; short rt_flags; short rt_refcnt; u_long rt_use; struct ifnet *rt_ifp; }; with rt_flags defined from: #define RTF_UP 0x1 /* route usable */ #define RTF_GATEWAY 0x2 /* destination is a gateway */ #define RTF_HOST 0x4 /* host entry (net otherwise) */ Routing table entries come in three flavors: for a specific host, for all hosts on a specific network, for any destination not matched by entries of the first two types (a wildcard route). When the system is booted, each network interface autoconfigured installs a routing table entry when it wishes to have packets sent through it. Normally the interface specifies the route through it is a ``direct'' connection to the destination host or network. If the route is direct, the transport layer of a protocol family usually requests the packet be sent to the same host specified in the packet. Otherwise, the interface may be requested to address the packet to an entity different from the eventual recipient (that is, the packet is forwarded). Routing table entries installed by a user process may not specify the hash, reference count, use, or interface fields; these are filled in by the routing routines. If a route is in use when it is deleted (rt_refcnt is non-zero), the resources associated with it will not be reclaimed until all references to it are removed. The routing code returns EEXIST if requested to duplicate an existing entry, ESRCH if requested to delete a non-existent entry, or ENOBUFS if insufficient resources were available to install a new route. The rt_use field contains the number of packets sent along the route. This value is used to select among multiple routes to the same destination. When multiple routes to the same destination exist, the least used route is selected. A wildcard routing entry is specified with a zero destination address value. Wildcard routes are used only when the system fails to find a route to the destination host and network. The combination of wildcard routes and routing redirects can provide an economical mechanism for routing traffic. SEE ALSO bsdsocket.library/IoctlSocket(), netutil/route protocols/tcp protocols/tcp NAME tcp - Internet Transmission Control Protocol SYNOPSIS #include <sys/socket.h> #include <netinet/in.h> int socket(AF_INET, SOCK_STREAM, 0) DESCRIPTION The TCP protocol provides reliable, flow-controlled, two-way transmission of data. It is a byte-stream protocol used to support the SOCK_STREAM abstraction. TCP uses the standard Internet address format and, in addition, provides a per-host collection of ``port addresses''. Thus, each address is composed of an Internet address specifying the host and network, with a specific TCP port on the host identifying the peer entity. Sockets utilizing the tcp protocol are either ``active'' or ``passive''. Active sockets initiate connections to passive sockets. By default TCP sockets are created active; to create a passive socket the listen() bsdsocket.library function call must be used after binding the socket with the bind() bsdsocket.library function call. Only passive sockets may use the accept() call to accept incoming connections. Only active sockets may use the connect() call to initiate connections. Passive sockets may ``underspecify'' their location to match incoming connection requests from multiple networks. This technique, termed ``wildcard addressing'', allows a single server to provide service to clients on multiple networks. To create a socket which listens on all networks, the Internet address INADDR_ANY must be bound. The TCP port may still be specified at this time; if the port is not specified the bsdsocket.library function will assign one. Once a connection has been established the socket's address is fixed by the peer entity's location. The address assigned the socket is the address associated with the network interface through which packets are being transmitted and received. Normally this address corresponds to the peer entity's network. TCP supports one socket option which is set with setsockopt() and tested with getsockopt(). Under most circumstances, TCP sends data when it is presented; when outstanding data has not yet been acknowledged, it gathers small amounts of output to be sent in a single packet once an acknowledgement is received. For a small number of clients, such as X Window System functions that send a stream of mouse events which receive no replies, this packetization may cause significant delays. Therefore, TCP provides a boolean option, TCP_NODELAY (from <netinet/tcp.h>, to defeat this algorithm. The option level for the setsockopt call is the protocol number for TCP, available from getprotobyname(). Options at the IP transport level may be used with TCP; SEE ALSO ip. Incoming connection requests that are source-routed are noted, and the reverse source route is used in responding. DIAGNOSTICS A socket operation may fail with one of the following errors returned: [EISCONN] when trying to establish a connection on a socket which already has one; [ENOBUFS] when the AmiTCP/IP runs out of memory for an internal data structure; [ETIMEDOUT] when a connection was dropped due to excessive retransmissions; [ECONNRESET] when the remote peer forces the connection to be closed; [ECONNREFUSED] when the remote peer actively refuses connection establishment (usually because no process is listening to the port); [EADDRINUSE] when an attempt is made to create a socket with a port which has already been allocated; [EADDRNOTAVAIL] when an attempt is made to create a socket with a network address for which no network interface exists. SEE ALSO bsdsocket.library/getsockopt(), bsdsocket.library/socket(), bsdsocket.library/bind(), bsdsocket.library/listen(), bsdsocket.library/accept(), bsdsocket.library/connect(), inet, ip, <sys/socket.h>, <netinet/tcp.h>, <netinet/in.h> HISTORY The tcp protocol stack appeared in 4.2BSD. protocols/udp protocols/udp NAME udp - Internet User Datagram Protocol SYNOPSIS #include <sys/socket.h> #include <netinet/in.h> int socket(AF_INET, SOCK_DGRAM, 0) DESCRIPTION UDP is a simple, unreliable datagram protocol which is used to support the SOCK_DGRAM abstraction for the Internet protocol family. UDP sockets are connectionless, and are normally used with the sendto() and recvfrom() calls, though the connect() call may also be used to fix the destination for future packets (in which case the recv() and send() function calls may be used). UDP address formats are identical to those used by TCP. In particular UDP provides a port identifier in addition to the normal Internet address format. Note that the UDP port space is separate from the TCP port space (i.e. a UDP port may not be ``connected'' to a TCP port). In addition broadcast packets may be sent (assuming the underlying network supports this) by using a reserved ``broadcast address''; this address is network interface dependent. Options at the IP transport level may be used with UDP; SEE ALSO ip. DIAGNOSTICS A socket operation may fail with one of the following errors returned: [EISCONN] when trying to establish a connection on a socket which already has one, or when trying to send a datagram with the destination address specified and the socket is already connected; [ENOTCONN] when trying to send a datagram, but no destination address is specified, and the socket hasn't been connected; [ENOBUFS] when the system runs out of memory for an internal data structure; [EADDRINUSE] when an attempt is made to create a socket with a port which has already been allocated; [EADDRNOTAVAIL] when an attempt is made to create a socket with a network address for which no network interface exists. SEE ALSO bsdsocket.library/getsockopt(), bsdsocket.library/recv(), bsdsocket.library/send(), bsdsocket.library/socket(), inet, ip HISTORY The udp protocol appeared in 4.2BSD.